Summary

Replaces the pull_request_target approach with a secure two-stage workflow that enables Percy visual regression snapshots for fork PRs without exposing secrets to untrusted code.

Background

Percy snapshots were silently failing for all external contributor PRs because GitHub withholds repository secrets from pull_request workflows triggered by forks — PERCY_TOKEN was always an empty string for fork PRs.

A first fix using pull_request_target was implemented, but due to a recent exploit of this pattern: fork code running in a privileged context poisoned the npm cache, which was later restored by a release workflow with id-token: write, enabling unauthorized npm publishes. Given that our ci.yml release job also has id-token: write, the risk profile was unacceptable.

Solution

Split Percy CI into two isolated workflow stages:

Stage 1 — percy-build.yml (triggered by pull_request, no secrets)

• Checks out the PR code via the standard pull_request event — no elevated privileges
• Detects which Skin components changed via the existing detect-changed-components action
• Builds a static Storybook from the PR's code
• Saves Percy metadata (component list, PR number) alongside the build
• Uploads everything as a short-lived GitHub Actions artifact

Stage 2 — percy.yml (triggered by workflow_run, has secrets)

• Only runs when Stage 1 completes successfully — cancelled or failed builds are skipped
• Checks out the base branch and installs dependencies from there — no fork code executes at this stage
• Posts a pending commit status to the PR immediately so the check is visible while Percy runs
• Downloads the pre-built Storybook artifact from Stage 1
• Reads the saved metadata; commit SHA and branch are sourced directly from the workflow_run event payload for reliability
• Runs percy storybook against the static artifact, filtered to changed components when applicable
• Posts a final success or failure commit status back to the PR regardless of outcome (if: always())
• PERCY_TOKEN only ever exists in this stage, in a fully trusted context

The main branch baseline job is unchanged — it continues to run snapshots:all on push to main.

Security Properties

• Fork code runs in Stage 1 with no secrets and no privileged context
• PERCY_TOKEN is fully isolated to Stage 2, which runs entirely from base-branch code
• Eliminates the cache poisoning vector that enabled the TanStack attack: Stage 1 and Stage 2 run in separate jobs with separate npm installs, so a poisoned cache from a fork PR cannot reach the privileged stage

Trade-offs

• Storybook is always built in full in Stage 1, with Percy filtering to changed components in Stage 2 via --include — slightly slower than the previous partial-build approach but required for the isolation model
• Percy status checks appear with a short delay after Stage 1 completes rather than inline with other PR checks